/***
MarkDoc Mini
============

It is just a tradition to begin with __Hello__ _World_!

This is a new text paragraph. I can also use asterisk instead of 
underscore to make the text **bold** or *italic*, but the latter
is not supported in Stata help files (supported in html,docx,pdf). 

You can separate  your document by adding a horizontal line,
which is shown below. The alternative syntax mentioned in 
are also covered:

- - -

How about line-breaks without adding a new paragraph? 
In Markdown you can do a line break  
by adding 2 or more spaces   
at the end of the line  
to indicate a line-break     
without creating a new paragraph! This means you should pay a 
careful attention to the spaces you put in the documentation. 
They are very meaningful in Markdown syntax!

Hyperlinks
----------

Visit the [Markdown's developer site](https://daringfireball.net/projects/markdown/dingus) 
to make yourself familiar with the Markdown syntax. Unfortunately, 
Stata's __putdocx__ and __putpdf__ do not yet support 
hyperlinks, but the Stata help files generated by MarkDoc 
can show hyperlinks. 

Adding Indention
----------------

You can also indent your text as well as do nested indention. 
Use the ">" sign at the beginning of the line to indent it.

> this is a Markdown indention

> > this is indention level 2

> > > this is indention level 3

Code lines and code blocks
--------------------------

Code is shown in monospace font in the documents. Usually it 
is also styled to make it distinct from the text paragraphs. 
If you wish to add a line of code, begin the line with 4:

    This is a code! Please **DO NOT** *INTERPRET* Markdown code
    This is another code line

If you have a code block of several lines, it is easier to 
place it in a code block as shown below. You don't have to 
indent the code block with 4 spaces, it's all done 
automatically. and of course, you can put a single line of 
code in it as well!

~~~
This is a code block! Please **DO NOT** *INTERPRET* Markdown code
This is another code line
~~~

There is no limit on how many paragraphs you can write. Just 
keep an empty line between paragraphs or the previous styled
text (header, code block, indented code, horizontal lines, etc.

Adding a list
-------------

making a list is easy. Just begin a line with a number, immediately 
followed by a dot. or a dash followed by a space. 

Stata's __putdocx__ and __putpdf__ do not support lists yet. 
I created a workaround to support Markdown lists 
But nested lists are not yet implemented because they look 
rather ugly without a decent support of lists in the document... 

1. This is a list
2. This is list 2
3. This is list 3

- This is unordered list
- This is also unordered list

Limitations
===========

Some of the Markdown syntax is __NOT__ yet supported by Stata's __putdocx__ or 
__putpdf__ commands. These limitations are:

1. Hyperlink 
2. Nested lists
3. Mathematical notations


Markdown Tables
===============

> __NOTE__: Markdown tables are not supported in Stata Help files

Markdown also supports tables! Currently 2 table flavors are 
recognized, but you can cooperate to increase the supported 
tables!

### The recommended format

This is the recommended format, that is also used by the 
__tbl__ command for generating dynamic tables (see below)

"Column1"|"Column2"|"Column3"     
:--------|:--------:|:--------:   
Cat|Soccer|Apple 
Dog|Basketball|Orange 
Ape|baseball|Banana 

You can also style a cell:

"Column1"|"Column2"|"Column3"     
:--------|:--------:|:--------:   
__Cat__|Soccer|Apple 
__Dog__|Basketball|Orange 
__Ape__|baseball|Banana 


### The alternative format (not recommended)

The alternative format requires more work to create and 
adjust. You don't really want to do it manually... 

| __Animals__ | __Sports__ | __Fruits__ |
|-------------|------------|------------|
| Cat         | Soccer     | Apple      |
| Dog         | Basketball | Orange     |
| Ape         | baseball   | Banana     | 



Adding a figure with caption
----------------------------

Adding a figure with markdown is simple. if we __assume__ that 
you have an image file in your current working directory named 
__graph.png__, we can easily include it in the document 
using the following syntax:

![Figure 1. This is a caption of graph.png](graph.png)

Next, I will introduce you to other commands that can be used 
to generate dynamic tables and include figures.

> of course, Stata help files are unable of rendering image files


Adding a figure dynamically
===========================

***/

// load the image into the document automatically
clear
sysuse auto
histogram price
img, title("Figure 1. say something about this figure")

/***
Adding a dynamic table
===========================

***/

sysuse auto, clear
foreach var of varlist weight price mpg {
	summarize `var'
	local `var'_mean : display %9.2f r(mean)
	local `var'_sd   : display %9.2f r(sd)
}

tbl ("Variable Name", "Mean", "SD" \              ///
     "__weight__", `weight_mean', `weight_sd' \   ///
     "__price__", `price_mean', `price_sd' \      ///
	 "__mpg__", `mpg_mean', `mpg_sd')             ///
    , title("Table 1. Summary of __weight__, __price__, and __mpg__ variables")

/***
The tbl command is very powerful and it allows you to take 
full control of your table. For example, you can format the 
text you wish to show in the cells, using exactly the same syntax 
as the __display__ comand in Stata!
***/

summarize price
return list
tbl ("Variable", "Observations", "Mean", "SD" \  ///
     "__price__", r(N), %9.2f r(mean), %9.2f r(sd))
		 
		 
/***
Dynamic text
===========================

There are two ways to write dynamic text in MarkDoc 
(and MarkDoc _mini_). The first is using the __txt__ command.
This is a powerful command that also allows styling the text. 
For example, I use the txt command to create a dynamic Markdown 
table below (not recommended, only for demonstration)
***/


local l1 Cat
local l2 Dog
local l3 Soccer
local l4 Basketball
local l5 Apple 
local l6 Orange
txt 										    ///
"| __Animals__ | __Sports__ | __Fruits__ |"  _n ///
"|-------------|------------|------------|"  _n ///
"| `l1'        | `l3'       | `l5'       |"  _n ///
"| `l2'        | `l4'       | `l6'       |"  _n

/***
I can use the __return list__ command to see what macros are returned by the 
`summarize` command. These values will be printed:
***/

summarize price
return list
txt "the mean of Price variable is " r(mean)
txt "the minimum value is " r(min) " and the maximum is "  r(max)


/***
Alternative procedure for dynamic text
--------------------------------------

There is, however, a smarter way that can be used when you 
execute a do-file in Stata:
***/

scalar a = 10.847958758976
matrix A = (1,2\ 3, 4)
scalar b = A[2,1]
local a = 999
sysuse auto, clear

/***
How about <!a!>?
-----------------

For example, we can show the value of the 10th observation 
of the __Price__ variable, which is <!price[10]!> 

You can also use this syntax to show a value of a 
macro <!`a'!> or Scalar <!b!>, even when they are extracted 
from a matrix, e.g. <!A[1,1]!> or <!A[2,2]!>!
***/

